Release 10.1A: OpenEdge Development:
Programming Interfaces

Handling namespaces

There are three kinds of namespaces:

A local namespace, which is one that is declared in that tag.
An inherited namespace, which is one specified in an ancestor tag. For example, a namespace declared by the root node can be used in the entire document.
The default namespace, which is an unspecified namespace (no prefix provided).

There are two ways for a namespace to be created when writing an XML document. They can be created implicitly when starting an element or they can be declared explicitly after a tag has been started. Implicit namespaces are created with the methods START-ELEMENT, WRITE-EMPTY-ELEMENT, and WRITE-DATA-ELEMENT. Explicit namespaces are created with the methods DECLARE-NAMESPACE or INSERT-ATTRIBUTE.

Table 21–2: Namespace variations

Method call example/ Resulting tag	Use case explanation
START-ELEMENT("name", "") <name>	Case: You supply an element name, but no namespace prefix and no namespace URI. Result: The element is written without a prefix and the default namespace will be used.
START-ELEMENT("prefix:name", "") <prefix:name>	Case 1: You supply an element name with a namespace prefix, but no namespace URI. The supplied prefix has been previously associated with a namespace URI. Result: The element is written with the supplied prefix and the previously associated namespace URI will be used.
START-ELEMENT("prefix:name", "") error	Case 2: You supply an element name with a namespace prefix, but no namespace URI. The supplied prefix has not been previously associated with a namespace URI. The STRICT attribute is set to TRUE. Result: The call generates an error. Only the default namespace can be set to an empty string (““).
START-ELEMENT("prefix:name", "") <prefix:name xmlns:prefix="">	Case 3: You supply an element name with a namespace prefix, but no namespace URI. The supplied prefix has not been previously associated with a namespace URI. The STRICT attribute is set to FALSE. Result: The element is written with the supplied prefix and an empty namespace is specified.
START-ELEMENT("name", "namespaceUri") <prefix:name>	Case 1: You supply an element name without a namespace prefix. You supply a namespaceUri that has been previously associated with a namespace prefix. Result: The element is written using the previously associated prefix and the declared namespace URI is used.
START-ELEMENT("name", "namespaceUri") <name xmlns="namespaceUri">	Case 2: You supply an element name without a namespace prefix. You supply a namespaceUri that has not been previously associated with a namespace prefix. Result: The element is written without a prefix and the namespaceUri is set to the namespace URI associated with the default namespace.
START-ELEMENT("prefix:name", "namespaceUri") <prefix:name>	Case 1: You supply an element name with a namespace prefix and a namespaceUri that has been previously associated with the supplied prefix. Result: The element is written with the supplied prefix and name and the previously associated namespace URI will be used. Since the namespace matching the supplied prefix and URI pair has already been declared, it will not be redeclared.
START-ELEMENT("prefix:name", "namespaceUri") <prefix:name xmlns:prefix="namespaceUri">	Case 2: You supply an element name with a namespace prefix and a namespaceUri. Either one or both of the namespace prefix and the namespace URI has already been used in a previous declaration, but the pair have not been declared together. Result: The element is written with the supplied prefix and name and namespaceUri declared. This amounts to the declaration of a new namespace.
START-ELEMENT("prefix:name", "namespaceUri") error	Case 3: You supply an element name with a namespace prefix and a namespaceUri. The namespace prefix matches the prefix used in the element, but the URIs do not match. The STRICT attribute is set to TRUE. Result: The method call generates an error message. Within an element, namespaces are like attributes and must be unique. Exception: In the case where the element’s URI is the empty string, the tag will be written with the supplied namespaceUri.
START-ELEMENT("prefix:name", "namespaceUri") <prefix:name xmlns:prefix="namespaceUri" xmlns:prefix="">	Case 4: You supply an element name with a namespace prefix and a namespaceUri. The namespace prefix matches the prefix used in the element, but the URIs do not match. The STRICT attribute is set to FALSE. Result: The tag will be written, but it will not be valid XML.
DECLARE-NAMESPACE("namespaceUri", "prefix") <qname xmlns:prefix="namespaceUri">	Case 1: You supply a new prefix and new namespaceUri that do not overlap with those declared in the element. Result: Creates the expected namespace without error.
DECLARE-NAMESPACE("namespaceUri", "prefix") <prefix:name xmlns:prefix="namespaceUri">	Case 2: The provided namespaceUri matches the namespace URI declared in the element and prefix matches the namespace prefix declared in the element. Result: Re-declaring an implicitly created namespace (the namespace declared in the element) does no harm and will not generate an error message.
DECLARE-NAMESPACE("namespaceUri", "prefix") <prefix:name xmlns:prefix="namespaceUri">	Case 3: namespaceUri is provided and the namespace URI declared in the element is the empty string (““), and the provided prefix matches the namespace prefix declared in the element. Result: The namespace is created without error. In other words, if you are going to explicitly create your namespaces, you do not need to provide the namespace URI when you create the element.
DECLARE-NAMESPACE("namespaceUri", "prefix") error	Case 4: namespaceUri is provided but it does not match the namespace URI declared in the element and the supplied prefix does match the namespace prefix declared in the element. The STRICT attribute is set to TRUE. Result: The method call generates an error. Within an element, namespaces are like attributes and must be unique.
DECLARE-NAMESPACE("namespaceUri", ""). <qname xmlns="namespaceUri">	Case 1: You provide only a namespaceUri and an empty string (““) as the namespace prefix. Result: You create the default namespace.
DECLARE-NAMESPACE("namespaceUri", ""). error	Case 2: The element has declared a default namespace with a different namespace URI than the one you provide with namespaceUri. The STRICT attribute is set to TRUE. Result: The method call generates an error. Within an element, namespaces are like attributes and must be unique.
DECLARE-NAMESPACE("namespaceUri", ""). <name xmlns="namepsaceUri" xmlns="namespaceUri">	Case 3: The element has declared a default namespace with a different namespace URI than the one you provide with namespaceUri. The STRICT attribute is set to FALSE. Result: The tag will be written, but it will not be valid XML.
DECLARE-NAMESPACE("", "prefix") error	Case 1: You provide an empty string (““) as the namespace URI and supply the prefix. The STRICT attribute is set to TRUE. Result: The method call generates an error. Only the default namespace can be declared as the empty string (““).
DECLARE-NAMESPACE("", "prefix") <qname xmlns:prefix="">	Case 2: You provide an empty string (““) as the namespace URI and supply a prefix that matches the namespace prefix declared in the element. The STRICT attribute is set to FALSE. Result: This can be useful when not running in STRICT mode to reset the element namespace prefix to the empty string (““).
DECLARE-NAMESPACE("", "prefix"). <prefix:name xmlns:prefix="namepsaceUri" xmlns:prefix="">	Case 3: You provide an empty string (““) as the namespace URI and supply a prefix. The STRICT attribute is set to FALSE. Result: The tag will be written, but it will not be valid XML.
DECLARE-NAMESPACE("", ""). <qname xmlns="">	Case 1: You provide an empty string (““) as the namespace URI and as the namespace prefix. Result: You create the default namespace as empty.
DECLARE-NAMESPACE("", ""). error	Case 2: The element has declared a specific default namespace and you provide namespaceUri which is the empty string (““). The STRICT attribute is set to TRUE. Result: The method call generates an error. Within an element, namespaces are like attributes and must be unique.
DECLARE-NAMESPACE("", ""). <name xmlns="namespaceUri" xmlns="">	Case 3: The element has declared a specific default namespace and you provide namespaceUri which is the empty string (““). The STRICT attribute is set to FALSE. Result: The tag will be written, but it will not be valid XML